W3C Baggage

摘要

本規格為表示和傳播與分散式請求或工作流程執行相關的一組應用程式定義的屬性，定義了一個標準。

這與追蹤上下文（Trace Context）規範是獨立的。Baggage 可以不依賴於是否使用分散式追蹤。本規格對應用程式定義的屬性的表示和傳播進行了標準化。相對地，追蹤上下文規範標準化了需要啟用分佈式追蹤情境所需的元數據的表示和傳播。

目前版本的 Baggage 規範主要針對由應用程式和服務實作，包括在瀏覽器內執行的網路應用程式。網路瀏覽器或用戶代理目前不在目標實作範疇內。

Ch1. 一致性

符合性 除了被標註為非規範性的章節外，本規格中所有的編寫指引、圖解、範例和註釋都是非規範性的。本規格中其他的所有內容則是規範性的。 本文檔中的關鍵字 "MAY"（可）、"MUST"（必須）、"MUST NOT"（不可）和 "SHOULD"（應）應按照 BCP 14 [RFC2119] [RFC8174] 的描述進行解釋，但僅當它們全部以大寫字母出現時，如此處所示。

Ch2. 概述

Baggage header代表與分佈式請求相關的一組用戶自定義的屬性。函式庫和平台SHOULD當傳播這一header。

Ch3. Baggage HTTP Header格式

Baggage header用於透過分散式請求傳播用戶提供的key-value pair。收到的header可以被更改以加入或修改資訊，並SHOULD被傳遞至所有下游的請求。

允許有多個 Baggage header。根據 RFC 7230，多個值可以在單一的header中合併。

3.1 Header名稱

Header名稱：baggage

為了提高在多個協議間的互通性和促使成功的整合，實作上SHOULD將標頭名稱保持為小寫。

3.2 Header內容

本節使用 [RFC5234] 的增強巴科斯-納爾格式（ABNF）表示法。

3.2.1 定義

baggage-string         =  list-member 0*179( OWS "," OWS list-member )
list-member            =  key OWS "=" OWS value *( OWS ";" OWS property )
property               =  key OWS "=" OWS value
property               =/ key OWS
key                    =  token ; as defined in RFC 7230, Section 3.2.6
value                  =  *baggage-octet
baggage-octet          =  %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
                          ; US-ASCII characters excluding CTLs,
                          ; whitespace, DQUOTE, comma, semicolon,
                          ; and backslash
OWS                    =  *( SP / HTAB ) ; optional white space, as defined in RFC 7230, 
Section 3.2.3

token is defined in [RFC7230], Section 3.2.6: https://tools.ietf.org/html/rfc7230#section-3.2.6

The definition of OWS is taken from [RFC7230], Section 3.2.3: https://tools.ietf.org/html/rfc7230#section-3.2.3

3.2.1.1 baggage-string

帶有可選屬性的 list-member 列表。在一個 baggage-string 中多個 list-member 之間的鍵的唯一性不保證。在變更列表時，SHOULD保留重複條目的順序。生產者SHOULD嘗試生成一個沒有任何與另一個 list-member 的鍵重複的 list-member 的 baggage-string。

3.2.1.2 Key

在 baggage 中識別一個值的token。在 RFC7230，第 3.2.6 節中有定義。首尾的空白（OWS）是允許的，並不被認為是鍵的一部分。

3.2.1.3 Value

一個包含MUST是 UTF-8 [編碼] 字符編碼的字符串的值。任何在 baggage-octet 字符範圍之外的字符必須進行百分比編碼。不需要進行百分比編碼的字符可以進行百分比編碼。百分比編碼在 [RFC3986]，https://datatracker.ietf.org/doc/html/rfc3986#section-2.1 第 2.1 節中有定義。

解碼值時，不符合 UTF-8 編碼方案的百分比編碼八位位元組序列MUST被替換為替代字符（U+FFFD）。

首尾的空白（OWS）是允許的，並不被認為是值的一部分。

注意，值MAY包含任何數量的等號（=）字符。解析器MUST NOT假定等號僅用於分隔鍵和值。

3.2.1.4 Proeperty

額外的元數據MAY以屬性集的形式附加到值上，表示為以分號 ; 分隔的鍵和/或鍵-值對列表，例如；k1=v1；k2；k3=v3。本規範未給屬性鍵和值賦予具體含義。首尾的 OWS 是允許的，並不被認為是屬性鍵或值的一部分。

3.2.2 限制

平台MUST傳播所有列表成員（list-members），包括由平台添加的任何列表成員，當以下兩個條件都滿足時：

• 條件 1：生成的 baggage-string 包含 64 個或更少的list-member。
• 條件 2：生成的 baggage-string 的大小為 8192 字節或更少。

如果上述任一條件不滿足，平台MAY選擇丟棄一些list-member，直到兩個條件都滿足。選擇哪些list-member要丟棄及其順序是未指定的，由實現者自行決定。需要注意的是，上述限制是符合規範的最低要求。實現者或平台MAY定義更高的限制，並SHOULD儘量傳播符合其要求的 baggage 信息。如果平台不能傳播所有 baggage，它MUST NOT傳播任何不完整的列表成員。如果有多個 baggage 頭部，所有限制適用於所有 baggage 頭部的組合，而不是每個頭部單獨適用。

3.2.3 範例

以下示例頭部包含 3 個list-member。Header中包含的 baggage-string 包含 86 bytes。其中 82 bytes來自list-member，4 bytes來自逗號和可選的空白。

baggage: key1=value1;property1;property2, key2 = value2, key3=value3; propertyKey=propertyValue

• key1=value1;property1;property2
  • 31 bytes
• key2 = value2
  • 13 bytes
• key3=value3; propertyKey=propertyValue
  • 38 bytes

3.3 Http Header的範例

假設我們想傳播以下資訊：userId="alice"，serverNode="DF 28"，isProduction=false，

單一Header：

baggage: userId=alice,serverNode=DF%2028,isProduction=false

這裡有一個更多的示例，其中值中含有超出 baggage-octet 字符範圍的字符，因此進行了百分比編碼。考慮以下資訊：userId="Amélie"，serverNode="DF 28"，isProduction=false：

baggage: userId=Am%C3%A9lie,serverNode=DF%2028,isProduction=false

上下文可能會被分割成多個headers：

baggage: userId=alice
baggage: serverNode=DF%2028,isProduction=false

Values和names可能會以空格開始和結束：

baggage: userId =   alice
baggage: serverNode = DF%2028, isProduction = false

3.3.1 範例用例

例如，如果您所有的數據需要發送到單一節點，您可以使用一個屬性來進行標示。

baggage: serverNode=DF%2028

例如，如果您需要用一些請求特定的信息來注釋日誌，您可以使用 baggage header來傳播一個屬性。

baggage: userId=alice

例如，如果您有非生產環境的請求也流經同樣的生產環境服務。

baggage: isProduction=false

3.4 修改Baggage

一個接收到 baggage 請求頭部的系統SHOULD將其發送到外發請求。該系統在傳遞之前MAY改變此header的值。

由於這裡沒有指定 baggage 資訊的key、value和元數據，生產者和消費者MAY就任何一組不違反規範的修改規則達成一致。例如，可以通過保留第一個資訊、保留最後一個資訊或將值連接在一起來消除重複的鍵。

允許以下修改：

• 添加一個新的鍵/值對。可以添加一個鍵/值對。
• 更新現有的值。任何給定鍵的值可以被更新。
• 刪除一個鍵/值對。任何鍵/值對都可以被刪除。
• 列表去重複。可以移除重複的鍵。

如果一個接收或更新 baggage 請求header的系統確定 baggage 資訊的數量超過了上面在限制部分定義的限制，則它MAY按照實現選擇的任何順序刪除或截斷某些 baggage 資訊。

如果系統確定某個 baggage 條目的值不符合本規範中定義的格式，則它MAY在將 baggage header作為外發請求的一部分傳播之前刪除該資訊。

Ch4. 安全性考量

依賴 baggage header的系統也應遵循解析潛在惡意數據的所有最佳實踐，包括檢查header長度和header值的內容。這些做法有助於避免緩衝區溢出、HTML 注入和其他類型的攻擊。

4.1 訊息暴露

如隱私部分所提到的，baggage 可能攜帶敏感訊息。應用程序所有者應確保沒有專有或機密訊息存儲在 baggage 中，或者他們應確保在跨越信任邊界的請求中不存在 baggage。

4.2 其他風險

應用程序所有者需要確保測試通往發送 baggage header的所有程式碼路徑。例如，在用 JavaScript 編寫的網絡應用中，通常會進行跨源請求。如果這些程式碼路徑之一導致跨源調用發送被 Access-Control-Allow-Headers [FETCH] 限制的 baggage header，則可能會失敗。

Ch5. 隱私性考量

要求將header資訊傳播到下游服務，以及存儲這些header的值，都引發了潛在的隱私問題。通過使用專有的上下文傳播方式，供應商和應用開發人員總是可以編碼包含用戶可識別數據的資訊。這個標準使系統能夠在跨越信任邊界時，操作一個已知的、標準化的header，以限制敏感數據在 baggage 中的傳播。

系統MUST評估header濫用的風險。本節提供了一些考慮因素和與存儲和傳播此header相關的風險的初步評估。系統可以選擇在處理或傳播接收到的數據之前，檢查並刪除欄位中的敏感信息。然而，所有的變更應符合本規範中定義的變更列表。

5.1 baggage header的隱私

這個header的主要目的是向相同信任邊界內的其他系統提供額外的系統特定信息。baggage header可能在任何鍵中包含任何值。因此，baggage header可能包含用戶可識別的數據，但本規範對任何鍵或其值或屬性不給予語義含義。使用 baggage 的應用程序應意識到，鍵和值可以被傳播到其他系統。因此，他們應刪除任何他們不希望被傳播到其他系統的私人信息。

總結

這個 W3C 的 Baggage 規範主要用於標準化分散式系統中用戶自定義屬性（Key-Value pair）的表示和傳播。這些屬性與追蹤上下文是獨立的，可以用於分散式請求或工作流程。

主要章節總結：

• 一致性（Ch1）：規範明確了哪些部分是規範性的，哪些是非規範性的。特定的關鍵字（如 "MUST"，"SHOULD" 等）有特定的意義。

• 概述（Ch2）：Baggage是用於傳播與分佈式請求相關的自定義屬性。應當支持這個header的傳播。

• Baggage HTTP Header 格式（Ch3）：

Header 名稱為 baggage，並應保持小寫。
詳細描述了 header 的內容格式。
定義了大小和數量的限制，不符合規範的可能會被丟棄。
修改 Baggage（Ch3.4）：系統在傳遞 Baggage 之前可以修改其內容，例如添加、更新或刪除鍵值對。

• 安全性考量（Ch4）：涉及檢查header長度和值以避免安全風險，並提醒應用程序所有者注意不要在baggage中存儲敏感或專有訊息。

• 隱私性考量（Ch5）：詳述了與傳播和存儲這些 header 相關的隱私問題，並要求系統必須評估 header 濫用的風險。

整體而言，這份規範主要是為了讓分佈式系統中的自定義屬性能有一個標準的表示和傳播方式。它涵蓋了格式、一致性、修改方式以及安全和隱私方面的考量。